home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / Tk / selection.z / selection
Text File  |  1998-10-30  |  10KB  |  199 lines
  1.  
  2.  
  3.  
  4. sssseeeelllleeeeccccttttiiiioooonnnn((((3333TTTTkkkk))))                                                  sssseeeelllleeeeccccttttiiiioooonnnn((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      selection - Manipulate the X selection
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      sssseeeelllleeeeccccttttiiiioooonnnn _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  13.  
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      This command provides a Tcl interface to the X selection mechanism and
  17.      implements the full selection functionality described in the X Inter-
  18.      Client Communication Conventions Manual (ICCCM).
  19.  
  20.      The first argument to sssseeeelllleeeeccccttttiiiioooonnnn determines the format of the rest of the
  21.      arguments and the behavior of the command.  The following forms are
  22.      currently supported:
  23.  
  24.      sssseeeelllleeeeccccttttiiiioooonnnn cccclllleeeeaaaarrrr ?----ddddiiiissssppppllllaaaayyyyooooffff _w_i_n_d_o_w? ?----sssseeeelllleeeeccccttttiiiioooonnnn _s_e_l_e_c_t_i_o_n?
  25.           If _s_e_l_e_c_t_i_o_n exists anywhere on _w_i_n_d_o_w's display, clear it so that  |
  26.           no window owns the selection anymore.  _S_e_l_e_c_t_i_o_n specifies the X    |
  27.           selection that should be cleared, and should be an atom name such as|
  28.           PRIMARY or CLIPBOARD; see the Inter-Client Communication Conventions|
  29.           Manual for complete details.  _S_e_l_e_c_t_i_o_n defaults to PRIMARY and     |
  30.           _w_i_n_d_o_w defaults to ``.''.  Returns an empty string.
  31.  
  32.      sssseeeelllleeeeccccttttiiiioooonnnn ggggeeeetttt ?----ddddiiiissssppppllllaaaayyyyooooffff _w_i_n_d_o_w? ?----sssseeeelllleeeeccccttttiiiioooonnnn _s_e_l_e_c_t_i_o_n? ?----ttttyyyyppppeeee _t_y_p_e?
  33.           Retrieves the value of _s_e_l_e_c_t_i_o_n from _w_i_n_d_o_w's display and returns  |
  34.           it as a result.  _S_e_l_e_c_t_i_o_n defaults to PRIMARY and _w_i_n_d_o_w defaults  |
  35.           to ``.''. _T_y_p_e specifies the form in which the selection is to be
  36.           returned (the desired ``target'' for conversion, in ICCCM
  37.           terminology), and should be an atom name such as STRING or
  38.           FILE_NAME; see the Inter-Client Communication Conventions Manual for
  39.           complete details.  _T_y_p_e defaults to STRING.  The selection owner may
  40.           choose to return the selection in any of several different
  41.           representation formats, such as STRING, ATOM, INTEGER, etc. (this
  42.           format is different than the selection type; see the ICCCM for all
  43.           the confusing details).  If the selection is returned in a non-
  44.           string format, such as INTEGER or ATOM, the sssseeeelllleeeeccccttttiiiioooonnnn command
  45.           converts it to string format as a collection of fields separated by
  46.           spaces: atoms are converted to their textual names, and anything
  47.           else is converted to hexadecimal integers.
  48.  
  49.      sssseeeelllleeeeccccttttiiiioooonnnn hhhhaaaannnnddddlllleeee ?----sssseeeelllleeeeccccttttiiiioooonnnn _s_e_l? ?----ttttyyyyppppeeee _t_y_p? ?----ffffoooorrrrmmmmaaaatttt _f_m_t? _w_i_n_d_o_w _c_o_m_m_a_n_d
  50.           Creates a handler for selection requests, such that _c_o_m_m_a_n_d will be |
  51.           executed whenever _s_e_l_e_c_t_i_o_n is owned by _w_i_n_d_o_w and someone attempts |
  52.           to retrieve it in the form given by _t_y_p_e (e.g. _t_y_p_e is specified in |
  53.           the sssseeeelllleeeeccccttttiiiioooonnnn ggggeeeetttt command).  _S_e_l_e_c_t_i_o_n defaults to PRIMARY, _t_y_p_e    |
  54.           defaults to STRING, and _f_o_r_m_a_t defaults to STRING.  If _c_o_m_m_a_n_d is an|
  55.           empty string then any existing handler for _w_i_n_d_o_w, _t_y_p_e, and        |
  56.           _s_e_l_e_c_t_i_o_n is removed.                                               |
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. sssseeeelllleeeeccccttttiiiioooonnnn((((3333TTTTkkkk))))                                                  sssseeeelllleeeeccccttttiiiioooonnnn((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.           When _s_e_l_e_c_t_i_o_n is requested, _w_i_n_d_o_w is the selection owner, and _t_y_p_e|
  75.           is the requested type, _c_o_m_m_a_n_d will be executed as a Tcl command    |
  76.           with two additional numbers appended to it (with space separators).
  77.           The two additional numbers are _o_f_f_s_e_t and _m_a_x_B_y_t_e_s:  _o_f_f_s_e_t
  78.           specifies a starting character position in the selection and
  79.           _m_a_x_B_y_t_e_s gives the maximum number of bytes to retrieve.  The command
  80.           should return a value consisting of at most _m_a_x_B_y_t_e_s of the
  81.           selection, starting at position _o_f_f_s_e_t.  For very large selections
  82.           (larger than _m_a_x_B_y_t_e_s) the selection will be retrieved using several
  83.           invocations of _c_o_m_m_a_n_d with increasing _o_f_f_s_e_t values.  If _c_o_m_m_a_n_d
  84.           returns a string whose length is less than _m_a_x_B_y_t_e_s, the return
  85.           value is assumed to include all of the remainder of the selection;
  86.           if the length of _c_o_m_m_a_n_d's result is equal to _m_a_x_B_y_t_e_s then _c_o_m_m_a_n_d
  87.           will be invoked again, until it eventually returns a result shorter
  88.           than _m_a_x_B_y_t_e_s.  The value of _m_a_x_B_y_t_e_s will always be relatively
  89.           large (thousands of bytes).
  90.  
  91.           If _c_o_m_m_a_n_d returns an error then the selection retrieval is rejected
  92.           just as if the selection didn't exist at all.
  93.  
  94.           The _f_o_r_m_a_t argument specifies the representation that should be used
  95.           to transmit the selection to the requester (the second column of
  96.           Table 2 of the ICCCM), and defaults to STRING.  If _f_o_r_m_a_t is STRING,
  97.           the selection is transmitted as 8-bit ASCII characters (i.e.  just
  98.           in the form returned by _c_o_m_m_a_n_d).  If _f_o_r_m_a_t is ATOM, then the
  99.           return value from _c_o_m_m_a_n_d is divided into fields separated by white
  100.           space;  each field is converted to its atom value, and the 32-bit
  101.           atom value is transmitted instead of the atom name.  For any other
  102.           _f_o_r_m_a_t, the return value from _c_o_m_m_a_n_d is divided into fields
  103.           separated by white space and each field is converted to a 32-bit
  104.           integer;  an array of integers is transmitted to the selection
  105.           requester.
  106.  
  107.           The _f_o_r_m_a_t argument is needed only for compatibility with selection
  108.           requesters that don't use Tk.  If Tk is being used to retrieve the
  109.           selection then the value is converted back to a string at the
  110.           requesting end, so _f_o_r_m_a_t is irrelevant.
  111.  
  112.      sssseeeelllleeeeccccttttiiiioooonnnn oooowwwwnnnn ?----ddddiiiissssppppllllaaaayyyyooooffff _w_i_n_d_o_w? ?----sssseeeelllleeeeccccttttiiiioooonnnn _s_e_l_e_c_t_i_o_n?
  113.           The first form of sssseeeelllleeeeccccttttiiiioooonnnn oooowwwwnnnn returns the path name of the window |
  114.           in this application that owns _s_e_l_e_c_t_i_o_n on the display containing   |
  115.           _w_i_n_d_o_w, or an empty string if no window in this application owns the|
  116.           selection.  _S_e_l_e_c_t_i_o_n defaults to PRIMARY and _w_i_n_d_o_w defaults to    |
  117.           ``.''.
  118.  
  119.      sssseeeelllleeeeccccttttiiiioooonnnn oooowwwwnnnn ?----ccccoooommmmmmmmaaaannnndddd _c_o_m_m_a_n_d? ?----sssseeeelllleeeeccccttttiiiioooonnnn _s_e_l_e_c_t_i_o_n? _w_i_n_d_o_w
  120.           The second form of sssseeeelllleeeeccccttttiiiioooonnnn oooowwwwnnnn causes _w_i_n_d_o_w to become the new    |
  121.           owner of _s_e_l_e_c_t_i_o_n on _w_i_n_d_o_w's display, returning an empty string as|
  122.           result. The existing owner, if any, is notified that it has lost the|
  123.           selection.  If _c_o_m_m_a_n_d is specified, it is a Tcl script to execute  |
  124.           when some other window claims ownership of the selection away from  |
  125.           _w_i_n_d_o_w.  _S_e_l_e_c_t_i_o_n defaults to PRIMARY.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. sssseeeelllleeeeccccttttiiiioooonnnn((((3333TTTTkkkk))))                                                  sssseeeelllleeeeccccttttiiiioooonnnn((((3333TTTTkkkk))))
  137.  
  138.  
  139.  
  140. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  141.      clear, format, handler, ICCCM, own, selection, target, type
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.